docs: clarify that supportingFiles is an allow-list (#22238) - #25075

Closes #22238.

What is actually going on

#22238 reports that the restclient library generates an ApiClient which
references ServerConfiguration / ServerVariable without those classes being
available, and suggests adding imports. Two things about that:

• They are in the same package as ApiClient (invokerPackage), so an
  import would not help — and would not compile.
• They are already registered as supporting files, and have been since
  [java] Support templated servers #4998: JavaClientCodegen.java:572-573 adds ServerConfiguration.mustache
  and ServerVariable.mustache, and :764 adds ExceptionProvider.mustache
  for restclient. A default run emits all of them next to ApiClient.java.

The reporter's build fails because of their own Maven configuration:

<supportingFilesToGenerate>ApiClient.java,Authentication.java,HttpBasicAuth.java,HttpBearerAuth.java,ApiKeyAuth.java,JavaTimeFormatter.java,RFC3339DateFormat.java</supportingFilesToGenerate>

That maps to the supportingFiles global property, which DefaultGenerator
treats as a fixed allow-list:

shouldGenerate = supportingFilesToGenerate.contains(support.getDestinationFilename());

The list was written before #21699 taught the restclient ApiClient about
servers, so ServerConfiguration.java, ServerVariable.java and
ExceptionProvider.java are now skipped while the emitted ApiClient still
references them. Reproduced with the CLI equivalent on a minimal spec: with
--global-property supportingFiles="ApiClient.java:..." exactly those three
files are missing from the output; without it, they are all generated and also
listed in .openapi-generator/FILES. @BobLuursema reached the same conclusion
in the issue thread.

So there is no generation bug to fix — but the trap is undocumented in the
places a user actually reads, and the Maven plugin's own Javadoc for the
option describes the wrong thing. This PR fixes that.

Changes

• docs/customization.md — new paragraph in Selective generation noting that
  an explicit list replaces the full set rather than adding to it, that
  supporting files reference one another (with the restclient ApiClient
  example), that each skip is logged at INFO level, and that
  .openapi-generator-ignore is the upgrade-safe alternative.
• docs/global-properties.md — one-line cross-reference to that caveat, since
  this is where supportingFiles is documented as a global property and where a
  user building the list reads first.
• CodeGenMojo.java — the Javadoc on supportingFilesToGenerate read "A comma
  separated list of models to generate. All models is the default.", copy-pasted
  from modelsToGenerate. Corrected, with the same caveat.
• modules/openapi-generator-maven-plugin/README.md — caveat added to the
  supportingFilesToGenerate row.
• JavaClientCodegenTest — two tests:
  • testRestClientSupportingFilesAllowListSkipsApiClientCompanions_issue_22238
    reproduces the reported configuration: with the supportingFiles global
    property set to ApiClient.java, ApiClient.java is still emitted while the
    ServerConfiguration, ServerVariable and ExceptionProvider it references
    are skipped. This pins and documents the footgun itself.
  • testRestClientDefaultGenerationIncludesCompanionFiles pins the premise the
    issue assumed had regressed — a default restclient run emits all four files
    side by side — so the registration cannot silently disappear.

No generator behaviour changes, so samples/ is untouched.

Testing

./mvnw -pl modules/openapi-generator -Dtest='JavaClientCodegenTest#testRestClientDefaultGenerationIncludesCompanionFiles+testRestClientSupportingFilesAllowListSkipsApiClientCompanions_issue_22238' clean test
./mvnw -pl modules/openapi-generator,modules/openapi-generator-maven-plugin clean test
./mvnw -pl modules/openapi-generator,modules/openapi-generator-maven-plugin checkstyle:check -Dcheckstyle.includeTestSourceDirectory=true

All green: the core library reports Tests run: 5270, Failures: 0, Errors: 0, Skipped: 14 with JavaClientCodegenTest at 299/0, the Maven plugin module
reports 27/0, and checkstyle passes with test sources included.

I also checked the default-generation test is meaningful: commenting out the
ServerConfiguration.mustache registration in JavaClientCodegen makes it fail
with File does not exist when it should: .../ServerConfiguration.java.

One note for anyone reproducing locally, since it cost me a round: the clean is
load-bearing. This repo enables the Develocity Maven extension with the local
build cache on, and a cached target/classes from before #24783 still contained
the ~30 mustache templates that commit moved from cpp-boost-beast-client/ to
cpp-boost-beast-common/. Maven's resources plugin never deletes removed files,
so the template locator resolved the stale copies and three unrelated tests
failed (cppboostbeast.ModelApiSurfaceTest and both
templating.GeneratorTemplateContentLocatorAdditionalDirsTest methods). They
pass on a clean build. Relatedly, mvn ... test compile cannot be used here at
all: the second lifecycle pass recompiles the antlr4-generated
KotlinLexer/KotlinParser against the compile classpath, where
antlr4-runtime is test-scoped, and it fails before the reactor reaches the
Maven plugin module.

PR checklist

• Read the contribution guidelines.
• Ran the build; samples and generator docs are unchanged by this PR
  (documentation and tests only), so there is nothing to regenerate.
• @Nicklas2751 (Java Spring 6 RestClient) — tagging you since the example in
  the docs is the restclient ApiClient you maintain; happy to reword.

Summary by cubic

Documents that the supportingFiles option is a fixed allow-list, not an addition, so an explicit list skips supporting files a newer generator version adds — which is what broke the build reported in #22238.

• Adds a paragraph to the selective generation docs, a cross-reference in docs/global-properties.md, and a recommendation to use .openapi-generator-ignore as the upgrade-safe alternative.
• Corrects the CodeGenMojo Javadoc for supportingFilesToGenerate (previously copy-pasted from modelsToGenerate) and the corresponding Maven plugin README row.
• The global-properties note states that supportingFiles, models, and apis are all allow-lists, but scopes the generator-upgrade warning to supportingFiles, since only its names are owned by the generator.
• Adds two tests: one reproducing the reported configuration to pin the allow-list behavior, and one verifying a default restclient run emits all referenced files.

No generator behavior changes; samples/ is untouched.

^{Written for commit 608b42c. Summary will update on new commits.}